Inside Macintosh: Open Transport /

Chapter 8 - TCP/IP Services / TCP/IP Services Reference

Functions / Retrieving DNS Query Information

OTInetQuery

Returns DNS query information.

C INTERFACE

OSStatus OTInetQuery  (InetSvcRef ref, char* name, UInt16 qClass, 
                       UInt16 qType, char* buf, size_t buflen, 
                       void** argv, size_t argvlen, OTFlags flags);

C++ INTERFACE

OSStatus TInternetServices::Query(char* name, UInt16 qClass, 
UInt16 qType, char* buf, size_t buflen, 
void** argv, size_t argvlen, OTFlags flags)

PARAMETERS

ref

The internet services reference you obtained when you opened the TCP/IP service provider.

name

A pointer to the fully qualified domain name or IP address for which you are asking the query.

qClass

The DNS query class, such as Inet and Hesiod, for which you wish to query.

qType

The DNS query type, such as CNAME and PTR, for which you wish to make a query.

buf

A pointer to the buffer in which to store one or more DNS query information structures (DNSQueryInfo). Open Transport fits as many complete structures into the buffer as it can; incomplete structures are not returned.

buflen

The size (in bytes) of the buffer.

argv

A pointer to an empty pointer array that Open Transport can use to return a set of pointers to the individual DNS query information structures returned. This parameter is optional, specify a null pointer if you don't want to use this array.

argvlen

The requested length of the argv buffer. On return, Open Transport updates this with the actual number of entries in the argv array. This parameter is optional; if you specify a null pointer for the argv parameter, this length is not returned.

flags

Reserved. Set to 0.

DESCRIPTION

The OTInetQuery function allows you to use the Domain Name Resolver (DNR) for generic domain name service (DNS) queries. You can ask for any query type and class, and Open Transport returns as many responses as it can fit in the buffer you provide.

The argv and argvlen parameters are optional. If provided, Open Transport uses the argv buffer to return pointers to the locations of individual answers written into the answer buffer pointed to by the buf parameter. For example, if you set argvlen to 5 and your query receives three answers, argvlen would be changed to 3, the value of argv[0] would be a pointer to the first answer in the answer buffer, the value of argv[1] would be a pointer to the second answer, the value of argv[2] would be a pointer to the third answer, and the rest of the argv array would have null pointers.

If you call OTInetQuery asynchronously, Open Transport calls your notifier with a T_DNRQUERYCOMPLETE event when the call completes. Asynchronous mode is preferred. When using asynchronous mode, you must not touch the buf or argv structures before the function completes.

The OTInetQuery function works with both known and unknown query classes and types. Open Transport expands compressed answers for the Inet query class and known query types before returning them into the answer buffer. Answers that are resource records of unknown class and type are put into the answer buffer unparsed because Open Transport assumes that DNS compression is not used.

Explicit simplified functions are provided for the most commonly made queries such as name-to-address (A), address-to-name (PTR), system CPU and OS (HINFO), and mail exchange (MX) queries. These are the OTInetStringToAddress, OTInetAddressToName, OTInetSysInfo, and OTInetMailExchange functions, respectively. For several basic query types, these functions may be easier to use. The information obtained is the same using either type of function, although in some cases the simplified functions limit the maximum number of answers that can be returned.

Currently, only answers of type PTR, A, and CNAME (name-to-address translations) are cached by OpenTransport. Also, OpenTransport does not currently use this cached information to resolve address-to-name translations because doing so would defeat some existing server load balancing schemes in operation today.

COMPLETION EVENT CODES

T_DNRQUERYCOMPLETE

0x10000005

The OTInetQuery function has completed.

SEE ALSO

Use the OTInetStringToAddress function for a simple name-to-address query (page 8-40), the OTInetAddressToName function for a simple address-to-name query (page 8-43), OTInetSysInfo function for a system CPU and OS query (page 8-44), and OTInetMailExchange function for a mail exchange query (page 8-45).